Defines a pointer to an icon getter callback function. Your icon getter callback function retrieves a handle to an icon of the requested type.

typedef Handle(* IconGetterProcPtr) (
    ResType theType, 
    void *yourDataPtr
);

You would declare your function like this if you were to name it MyIconGetterCallback:

Handle MyIconGetterCallback (
    ResType theType, 
    void *yourDataPtr
);

theType

The resource type of the icon. In general, you should specify your icon resources as purgeable.

yourDataPtr

If your icon getter function was called by an icon cache function, this parameter contains, on return, a pointer to the data associated with the icon cache. Otherwise, this parameter contains the value your application specified in the yourDataPtr parameter. For icon caches, you initially set this value when you first create a cache using the MakeIconCache function. You can change this value using the SetIconCacheData function. The icon getter function can use this data as needed.

function result

An icon getter function should return as its function result a handle to the requested icon’s data.

DISCUSSION

If you use icon caches, you must provide at least one icon getter function. The MakeIconCache function takes a pointer to an icon getter function for use with a new icon cache. Subsequent calls to Icon Utilities functions that use icon types not present in the icon cache use the icon getter function associated with the icon cache to return a handle to the icon data. To get and set an existing icon cache’s icon getter function, use the GetIconCacheProc and SetIconCacheProc functions.

You can also specify an icon getter function for use by the PlotIconMethod, IconMethodToRgn, PtInIconMethod, and RectInIconMethod functions. Like Icon Utilities functions that work with icon caches, the icon getter function that you provide as a parameter to PlotIconMethod should return a handle to the requested icon’s data. Note that the icon getter function that you provide as a parameter to IconMethodToRgn, PtInIconMethod, and RectInIconMethod should also return a handle to the requested icon; these three functions then extract the icon mask from the icon data your icon getter function returns.

The pointer which you pass to Icon Utilities functions using icon getter callback functions should be a universal procedure pointer (UPP). The definition of the UPP type for your icon getter callback function is as follows:

typedef (IconGetterProcPtr) IconGetterUPP;

Before using your icon getter function, you must first create a new universal procedure pointer to it, using the NewIconGetterUPP function, as shown here:

IconGetterUPP MyIconGetterUPP;

MyIconGetterUPP = NewIconGetterUPP(&MyIconGetterProc);

You can then pass MyIconGetterUPP to any of the Icon Utilities functions which use custom icon getter functions. If you wish to call your own icon getter function, you may use the InvokeIconGetterUPP function:

theIcon = InvokeIconGetterUPP(theType, &myData, MyIconGetterUPP);

When you are finished with your icon getter callback function, you should dispose of the universal procedure pointer associated with it, using the DisposeIconGetterUPP function:

DisposeIconGetterUPP(MyIconGetterUPP);

AVAILABILITY

Supported in Carbon.

© 2000 Apple Computer, Inc. — (Last Updated 4/18/2000)